> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jaypopat/cf_ai_duet/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/rooms/{roomID}/sandbox/exec

> Execute a shell command directly in the room's sandbox environment

Executes a shell command in the isolated sandbox environment associated with a room. Unlike the message endpoint, this executes commands directly without AI interpretation.

## Endpoint

```
POST /api/rooms/{roomID}/sandbox/exec
```

## Path Parameters

<ParamField path="roomID" type="string" required>
  Unique identifier for the room. Each room has its own isolated sandbox instance named `sandbox-{roomID}`.
</ParamField>

## Request Body

<ParamField body="cmd" type="string" required>
  The shell command to execute. Must be at least 1 character long.

  ```typescript theme={null}
  cmd: z.string().min(1, "Command cannot be empty")
  ```
</ParamField>

## Response

<ResponseField name="result" type="ExecResult">
  The execution result containing stdout and stderr streams.

  <Expandable title="ExecResult Schema">
    <ResponseField name="stdout" type="string">
      Standard output from the command execution
    </ResponseField>

    <ResponseField name="stderr" type="string">
      Standard error output from the command execution
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sandboxName" type="string">
  The name of the sandbox instance that executed the command (format: `sandbox-{roomID}`).
</ResponseField>

## Example Request

```bash theme={null}
curl -X POST https://your-worker.workers.dev/api/rooms/room-123/sandbox/exec \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": "echo 'Hello from sandbox'"
  }'
```

## Example Response

```json theme={null}
{
  "result": {
    "stdout": "Hello from sandbox\n",
    "stderr": ""
  },
  "sandboxName": "sandbox-room-123"
}
```

## Error Responses

### 400 Bad Request

Returned when request validation fails:

```json theme={null}
{
  "error": "invalid request",
  "details": {
    "cmd": ["Command cannot be empty"]
  }
}
```

### 404 Not Found

Returned when the room ID is missing or the endpoint path is incorrect.

### 405 Method Not Allowed

Returned when using a method other than POST.

### 500 Internal Server Error

Returned when sandbox execution fails:

```json theme={null}
{
  "error": "sandbox execution failed: <error details>"
}
```

## Use Cases

* Direct command execution for scripting and automation
* Testing and debugging sandbox environments
* File system operations in the isolated environment
* Running build commands or test suites

## Implementation Reference

The handler uses Cloudflare's sandbox API:

```typescript theme={null}
// cf-worker/index.ts:210-242
const sandbox = getSandbox(this.env.Sandbox, `sandbox-${roomId}`);
const result = await sandbox.exec(data.cmd);
return Response.json({ result, sandboxName });
```

## Sandbox Lifecycle

Each room has a persistent sandbox instance that:

* Is created on first use
* Maintains file system state between commands
* Is isolated from other rooms' sandboxes
* Can be destroyed using the [DELETE /api/rooms/{roomID}](/api/room-cleanup) endpoint

## Related Endpoints

* [POST /api/rooms/{roomID}/message](/api/message-endpoint) - Send messages to AI (which may execute commands)
* [DELETE /api/rooms/{roomID}](/api/room-cleanup) - Destroy the sandbox and clean up room state